Skip to main content
Expert Talk
Amakomaya — Aamako Maya Apps Pvt. Ltd.

Reference Architecture Template

Copy the structure below. The guidance under each heading says what belongs there and what commonly goes wrong; delete it as you write.

For a solution architecture, use the same structure and name technologies specifically. For a reference architecture, name components rather than products.

Document header​

# <Name> Reference Architecture

- **Version:** 0.1
- **Status:** Draft | For review | Approved | Superseded
- **Date:** YYYY-MM-DD
- **Owner:** <name, role>
- **Approved by:** <body, date>
- **Supersedes:** <document, version>

1. Executive summary​

One page. What this architecture is for, the main decisions, and what it will cost. Written for someone who will read nothing else — which describes most of your audience.

Write it last.

2. Problem statement​

The health problem, not the technology problem. "Women are lost to follow-up between antenatal contacts because records do not move with them" — not "we need an interoperability layer".

State the current situation with evidence, and what happens if nothing changes.

3. Objectives​

Measurable outcomes. What would have to be observably different for this to have been worth doing. If nobody can name these, stop here.

4. Scope​

What is in and — more usefully — what is out. Name the systems, workflows, populations, geographies and timeframes. Explicit exclusions prevent the scope creep that kills these programmes.

5. Stakeholders​

Who is affected, who decides, who pays, who operates, who must agree. Include those who will resist and why; an architecture that has not accounted for opposition has not accounted for reality.

6. Business architecture​

The health services delivered, the organisations delivering them, and the outcomes they are accountable for. Independent of software. See enterprise architecture.

7. Capability architecture​

What the system must be able to do, expressed independently of products. Include the capability-to-system map showing gaps and overlaps — the most valuable single table in this document.

8. Process architecture​

The priority workflows, with organisational handoffs marked, because every handoff is an integration requirement. BPMN where the model will be reused, swimlanes otherwise.

9. Information architecture​

Definitions: what is a patient, an encounter, a facility, an episode. Which identifier is authoritative for each. These are the most expensive decisions in the document.

10. Data architecture​

Canonical, logical and physical models. Master data ownership — one source of truth per domain. Operational versus analytical separation. Retention. See data architecture.

11. Application architecture​

Which system provides which capability, what it owns as master data, what it consumes. Include systems being retired and the transition.

12. Integration architecture​

How systems communicate: patterns, protocols, the mediating components. Include a diagram with protocol, format and synchronicity on every arrow.

13. Interoperability architecture​

Standards and versions, implementation guides, terminology bindings, conformance requirements. Address all four levels of interoperability — including the organisational one.

14. Security architecture​

Identity types, authentication, authorisation model, encryption, key management, threat model, audit. See security architecture.

15. Technology architecture​

Runtime, languages, databases, middleware. For a reference architecture, state constraints and required properties rather than products.

16. Infrastructure​

Hosting model, data residency, network topology, environments, capacity and growth projection. See infrastructure.

17. Governance​

Who decides what, which bodies exist, how changes are approved, how conformance is enforced. See governance.

18. Standards​

The standards register for this architecture: standard, version, where it applies, and the upgrade policy.

19. Deployment​

Environments, release process, change tiers by clinical risk, rollback, migration and cutover.

20. Availability​

Availability tier per component, set by clinical consequence. Degraded-mode behaviour for every component on the critical path — this section is frequently omitted and is where clinical safety lives.

21. Disaster recovery​

RTO and RPO per system, backup strategy including an immutable copy, restore testing, failover procedure, and the clinical continuity plan.

22. Monitoring​

Technical and business-level signals, SLOs, alerting, and who responds. Include the rule that personal health data stays out of telemetry. See observability.

23. Data governance​

Ownership, stewardship, quality metrics and accountability, access decisions, secondary use, retention and disposal.

24. Privacy​

Legal basis per data flow, consent model, purpose of use, break-glass, data minimisation, de-identification, patient access to their own audit trail.

25. AI governance​

If AI is in scope: inventory, clinical ownership, intended use, evaluation, monitoring, stopping rules, review cycle. If it is not in scope, say so — it will be proposed later.

26. Risks​

Risk, likelihood, impact, mitigation, owner. Include the risks that are uncomfortable to write: no legal basis, no sustainable funding, key person dependency, vendor lock-in, capacity to operate what is being built.

27. Architecture decisions​

The ADRs underpinning this document, listed with number, title and status. Do not inline them; link them.

28. Implementation roadmap​

Phases, each delivering something usable to a real user. Dependencies, sequencing rationale, and what each phase requires that does not yet exist.

Sequence to reduce risk, not to demonstrate progress. The registry-first argument applies to most health architectures.

Appendices​

  • Glossary (or link to the shared glossary)
  • Diagrams — C4 context and container as a minimum
  • Data dictionary or a link to it
  • Conformance requirements
  • Cost model
  • References

Review checklist​

Before circulating:

  • Someone who was not involved can read section 1 and explain the point
  • Section 2 describes a health problem, not a technology gap
  • Section 3 objectives are measurable
  • Section 4 says what is out of scope
  • Section 9 names the authoritative identifiers
  • Section 13 names implementation guides, not just "FHIR"
  • Section 20 defines degraded mode for every critical component
  • Section 24 states a legal basis, not an intention to obtain one
  • Section 26 includes the uncomfortable risks
  • Section 28 phase one delivers value to a named user
  • Every diagram has a title, a legend and a date
  • Every decision of consequence has an ADR

Then run the relevant checklists.

Last updated on